Inside Macintosh: Macintosh Human Interface Guidelines / Part 2 - The Interface Elements: Chapter 11 - Language

User Documentation

Documentation for users is an essential part of the user interface that you provide. Try to give it the same degree of consideration and attention that you give to your application's user interface. Consider the audience that you address with your product and tailor the documentation to its needs. It's often useful to provide alternate types of documentation for the different types of users who make up your audience. Beginners have different needs from those of expert users.

Plan an overall learning path for your users. This can help target your documentation to specific types of users. A well-designed learning path can help users approach the documentation according to their style of learning. For example, some users may want to be shown exactly how to do something and they may have an easier time learning about a product by practicing using it. A tutorial would be perfect for this type of user. Other users may want to explore and learn by their mistakes; they may read the documentation only to learn about advanced features or to troubleshoot a specific problem. A specific task-oriented set of instructions would be ideal for this type of user. The following list presents a general model for a learning path.

Setting up or installing the product.
Provide easy-to-follow, brief instructions that help users to set up the hardware and install the software necessary to begin using the product.
Learning how to use the product.
Include a tutorial that introduces core concepts and fundamental skills, and that explains why a user would want to use the product. Ideally this kind of information should be interactive and lead users, via a series of exercises, through several scenarios where they can learn the most common features of the product.
Using the product.
Provide detailed instructions about how to accomplish specific tasks, troubleshoot problems, and take advantage of advanced features.

Develop task-oriented documentation that teaches users how to accomplish the tasks that you designed your application to perform. Avoid system-oriented documentation that describes everything that your application can do rather than teaching practical skills.

Use standard terminology and nontechnical language in user documentation. Don't pass on technical jargon to users; they may not understand it. When you must use technical terms, be sure to define them at first occurrence, and include a glossary if your document has many specialized terms. Be consistent in your use of terminology. Make sure that messages and terms that users see on the screen match what appears in the documentation.

When you localize your software product, you'll need to translate all user documentation, including tutorials, online help, and books. Making your documentation available in a user's native language greatly enhances the usability and marketability of your product.

Tutorials, manuals, online help, and other forms of documentation cannot compensate for an interface that is hard to use. Documentation can't "fix" problems that need to be resolved in the interface itself. Thus, try to treat all documentation as part of the end user product and as part of the interface with which users must interact.